/**
 * Copyright (C) 2010 EduSubmit Team (Ersin Er, Sukru Tikves)
 * 
 * This work can be distributed under the terms of 
 * GNU Library General Public License (LGPL) v2.1
 */
package info.edusubmit.services.contracts;

import java.security.AccessControlException;

/**
 * @author Sukru
 *
 */
public interface CourseService {
	/**
	 * Returns a list of courses the given authenticated user is registered to.
	 * @param token Authentication token
	 * @return Course list
	 * @throws AuthenticationException when authentication is not valid.
	 */
	String[] getCourseListForUser(String token) throws AuthenticationException;
	
	/**
	 * Returns a list of accessible assignments in the given course for an authenticated user.
	 * @param token Authentication token
	 * @param course Course if
	 * @return Assignment list
	 * @throws AuthenticationException when authentication is not valid.
	 */
	String[] getOpenAssignmentList(String token, String course) throws AuthenticationException;
	
	/**
	 * Returns the configuration for a given assignment.
	 * @param token Authentication token
	 * @param assignment Assignment id
	 * @return Associated {@link AssignmentInformation} structure.
	 * @throws AuthenticationException when authentication is not valid or the user does not have sufficient rights for this action.
	 */
	AssignmentInformation getAssignmentInformation(String token, String assignment) throws AuthenticationException;
	
	/**
	 * Updates the configuration for a given assignment.
	 * @param token Authentication token
	 * @param assignment Assignment id
	 * @param newInfo New {@link AssignmentInformation} to be stored. Any non-changed value can be null.
	 * @throws AccessControlException when authentication is not valid or the user does not have sufficient rights for this action.
	 */
	void updateAssignment(String token, String assignment, AssignmentInformation newInfo) throws AccessControlException;
	
	/**
	 * Returns the upload file format description for a given assignment. 
	 * @param token Authentication token
	 * @param assignment Assignment id
	 * @return Associated upload file format
	 * @throws AccessControlException when authentication is not valid or the user does not have sufficient rights for this action.
	 */
	String getFileFormat(String token, String assignment) throws AccessControlException;
	
	/**
	 * Updated the upload file format description for a given assignment.
	 * @param token Authentication token
	 * @param assignment Assignment id
	 * @param newFormat New file format description
	 * @throws AccessControlException when authentication is not valid or the user does not have sufficient rights for this action.
	 */
	void setFileFormat(String token, String assignment, String newFormat) throws AccessControlException;
	
	/**
	 * Creates a new assignment with the given {@link AssignmentInformation} structure. 
	 * @param token Authentication token
	 * @param newInfo New {@link AssignmentInformation} to be stored. Any non-changed value can be null.
	 * @throws AccessControlException when authentication is not valid or the user does not have sufficient rights for this action.
	 */
	void newAssignment(String token, AssignmentInformation newInfo) throws AccessControlException;
	
	/**
	 * Returns whether an authenticated user can administer the given course.
	 * @param token Authentication token
	 * @param course Course id
	 * @return True if user has sufficient rights, False otherwise
	 * @throws AuthenticationException when authentication is not valid.
	 */
	Boolean canAdministerCourse(String token, String course) throws AuthenticationException;
	
	/**
	 * Returns whether an authenticated user can administer the given assignment.
	 * @param token Authentication token
	 * @param assignment Assignment id
	 * @return True if user has sufficient rights, False otherwise
	 * @throws AuthenticationException when authentication is not valid.
	 */
	Boolean canAdministerAssignment(String token, String assignment) throws AuthenticationException;
	
	/**
	 * Returns whether an authenticated user can make a file upload for the given assignment.
	 * @param token Authentication token
	 * @param assignment Assignment id
	 * @return True if user has sufficient rights, False otherwise
	 * @throws AuthenticationException when authentication is not valid.
	 */
	Boolean canUpload(String token, String assignment) throws AuthenticationException;
	
	/**
	 * Returns whether an authenticated user can access all the file uploads for a given assignment.
	 * @param token Authentication token
	 * @param assignment Assignment id
	 * @return True if user has sufficient rights, False otherwise
	 * @throws AuthenticationException when authentication is not valid.
	 */
	Boolean canDownloadAll(String token, String assignment) throws AuthenticationException;
}
